# Your Command Center: UserSessions

Remember Alex from our authentication story? Now that they're connected, the cloud creates a UserSession - their personal command center. Think of it as a smart assistant that manages everything happening with their glasses.

## What is a UserSession?

A UserSession is the heart of a user's experience in MentraOS Cloud. It's a long-lived object that:
- Maintains the WebSocket connection to the glasses
- Manages all the specialized services (managers)
- Tracks which apps are running
- Handles all message routing
- Survives temporary disconnections

```typescript
// Simplified view of UserSession
class UserSession {
  userId: string;                    // alex@example.com
  websocket: WebSocket;              // Connection to glasses
  appWebsockets: Map<string, WebSocket>; // Connections to apps
  startTime: Date;                   // When session started
  
  // The managers (our departments)
  appManager: AppManager;
  audioManager: AudioManager;
  displayManager: DisplayManager;
  // ... and more
}
```

## Meet the Managers

Think of managers as specialized departments in Alex's personal cloud office. Each one handles a specific type of functionality:

### 🎯 AppManager - The App Orchestrator

Manages the lifecycle of third-party apps:

```typescript
// What it tracks for each app
{
  packageName: "com.translate.app",
  state: "RUNNING" | "GRACE_PERIOD" | "RESURRECTING" | "STOPPING",
  websocket: WebSocket,
  lastHeartbeat: Date
}
```

**Key Responsibilities:**
- Starting and stopping apps
- Monitoring app health with heartbeats
- Handling app reconnections
- Managing the 20-second grace period when apps disconnect

**Real Example:**
When Alex says "Start translator", AppManager:
1. Finds the translator app in installed apps
2. Notifies the app via webhook to start
3. Waits for app to connect via WebSocket
4. Monitors the app's health

### 🎤 AudioManager - The Sound Department

Handles all things audio:

```typescript
// Managing audio streams
audioManager.startStreaming();  // Start receiving audio from glasses
audioManager.stopStreaming();   // Stop audio stream
audioManager.playAudio(audioData, format); // Play audio on glasses
```

**Key Responsibilities:**
- Receiving audio streams from glasses microphone
- Buffering audio data for processing
- Sending audio to glasses speakers
- Managing audio format conversions

### 📺 DisplayManager - The Visual Controller

Controls what appears on the glasses display:

```typescript
// Display update request
displayManager.updateDisplay({
  type: "cards",
  cards: [{
    title: "Weather",
    body: "72°F and sunny"
  }]
});
```

**Key Responsibilities:**
- Rendering layouts from apps
- Enforcing the 200-300ms throttle between updates
- Managing display queues
- Preventing display spam

**Important:** The glasses have a simple display that can only show text. No images, no colors (except green), just text and simple layouts.

### 🎙️ TranscriptionManager - The Speech-to-Text Expert

Converts speech to text in real-time:

```typescript
// Start transcribing
transcriptionManager.startTranscription("en-US");

// Receive transcription events
transcriptionManager.on('transcription', (text) => {
  console.log("User said:", text);
});
```

**Key Responsibilities:**
- Managing transcription providers (Deepgram, Assembly, etc.)
- Streaming audio to transcription services
- Handling multiple language streams
- Distributing transcripts to subscribed apps

### 📸 PhotoManager - The Camera Controller

Handles photo capture:

```typescript
// App requests a photo
photoManager.requestPhoto();

// Photo arrives from glasses
photoManager.on('photoReceived', (photoData) => {
  // Process and distribute to requesting app
});
```

### 🌐 MicrophoneManager - The Audio Gate

Controls the glasses microphone:

```typescript
// Turn microphone on/off
microphoneManager.setMicrophoneState(true);  // On
microphoneManager.setMicrophoneState(false); // Off
```

### 📊 DashboardManager - The Always-On Display

Manages the dashboard mode (always-visible information):

```typescript
// Update dashboard content
dashboardManager.updateContent({
  text: "3 new messages",
  priority: "high"
});
```

## How Managers Work Together

Let's see how managers collaborate when Alex says "Take a photo":

1. **AudioManager** receives the audio stream
2. **TranscriptionManager** converts it to text: "Take a photo"
3. **AppManager** routes the transcript to subscribed apps
4. App recognizes the command and tells **PhotoManager**
5. **PhotoManager** sends photo request to glasses
6. Glasses capture photo and send it back
7. **PhotoManager** receives photo and gives it to the app
8. App processes photo and uses **DisplayManager** to show "Photo saved!"

## Session Lifecycle

### Birth: Session Creation

When Alex connects:
```typescript
const session = new UserSession(userId, websocket);
// All managers are initialized
session.appManager = new AppManager(session);
session.audioManager = new AudioManager(session);
// ... etc
```

### Life: Active Session

During normal operation:
- Heartbeat runs every 10 seconds
- Messages flow between glasses and apps
- Managers handle their specific duties
- Everything is logged for debugging

### Near-Death: Disconnection

When connection drops:
- 30-second grace period begins
- Apps enter "resurrecting" state
- Session waits for reconnection
- No data is lost

### Resurrection or Death

**If Alex reconnects within 30 seconds:**
- WebSocket is updated
- Apps are notified
- Everything continues normally

**If Alex doesn't reconnect:**
- Session is cleaned up
- All managers are destroyed
- Apps are notified of session end
- Memory is freed

## Session Storage

All active sessions live in SessionStorage:

```typescript
class SessionStorage {
  private static sessions = new Map<string, UserSession>();
  
  static getSession(userId: string): UserSession | undefined {
    return this.sessions.get(userId);
  }
  
  static addSession(session: UserSession) {
    this.sessions.set(session.userId, session);
  }
}
```

This allows any part of the system to find Alex's session when needed.

## Best Practices

1. **Always check session exists** before using it
2. **Use the appropriate manager** for each task
3. **Let managers handle their domain** - don't bypass them
4. **Clean up resources** when sessions end
5. **Log important events** for debugging

## What's Next?

Now that you understand UserSessions and their managers, let's look at [the messages](./4-message-types.md) that flow through the system. These messages are how all the components talk to each other!